home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.103 < prev    next >
Encoding:
Text File  |  1992-07-15  |  4.1 KB  |  131 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #103: Inline Procedure Name Format
  7.  
  8. Modified by: Matt Deatherage                                        May 1992
  9. Written by:  Dave Lyons                                        December 1991
  10.  
  11. This Technical Note describes a simple format for imbedding procedure names in
  12. object code, for use by debugging utilities.
  13.  
  14. CHANGES SINCE DECEMBER 1991:  Changed &syscnt to &SYSCNT so it works with the
  15. CASE ON APW directive.  Clarified the possible addition of parameters after
  16. the Pascal string.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. GSBug 1.5b18 and later support a simple convention for including procedure
  21. names inline in the object code, for debugging purposes.
  22.  
  23.  
  24. INLINE NAME FORMAT
  25.  
  26.        82 xx xx                     brl  pastName
  27.        71 77                        dc.w $7771
  28.        nn xx xx xx xx...            str  'the name string'
  29.                           pastName  ...
  30.  
  31. That is, an imbedded name is a BRL around a signature word and a Pascal
  32. string.  The name string can theoretically be up to 255 characters long, but
  33. in practice only short names are useful.  For example, GSBug displays only the
  34. first 15 characters of a name when it is encountered, and only the first 11
  35. when it appears as the operand of a JSR or JSL instruction.
  36.  
  37. Names in this format always start with a BRL, not a BRA or JMP.  Signature
  38. word values other than $7771 are reserved for future definition, and more
  39. information may be added after the Pascal string.
  40.  
  41. Be careful what you name!
  42.  
  43. Be careful not to name something important--like a table, or a label from
  44. which you compute other addresses.  The extra bytes generated by the inline
  45. name would mess up your calculations.  If you name a heartbeat task,
  46. out-of-memory queue routine, or other construction that needs a special
  47. header, be sure to put the name where the executable code starts, not at the
  48. beginning of the header.
  49.  
  50. APW ASSEMBLY MACRO
  51.  
  52. The following macro is for the APW assembler.  If you equate DebugSymbols to
  53. zero, the macro generates no object code.  If DebugSymbols is nonzero, the
  54. macro generates an inline name corresponding to its label.
  55. Use the name macro anywhere you would use a label.  For example:
  56.  
  57. DebugSymbols   GEQU 1
  58. ...
  59. CountItems     name
  60.  
  61. The macro:
  62.  
  63.      MACRO
  64. &lab name
  65. &lab anop
  66.      aif DebugSymbols=0,.pastName
  67.      brl pastName&SYSCNT
  68.      dc i'$7771'
  69.      dc i1'L:&lab',c'&lab'
  70. pastName&SYSCNT anop
  71. .pastName
  72.      MEND
  73.  
  74.  
  75. MPW IIgs Assembly Macros
  76.  
  77. The following macros are for the MPW IIgs assembler.  If you equate
  78. DebugSymbols to zero, the macros generate no object code.  If DebugSymbols is
  79. nonzero, the macros generate inline names corresponding to their labels.
  80.  
  81. Use the name macro anywhere you would use a label.  Use the procname macro in
  82. place of a proc directive, at the beginning of a procedure.  For example:
  83.  
  84. DebugSymbols   equ 1
  85. ...
  86. CountItems     name
  87. TaskLoop       procname
  88.  
  89. The macros:
  90.  
  91.               macro
  92. &lab          name
  93. &lab
  94.               if DebugSymbols<>0 then
  95.               brl @pastName
  96.               lclc &olds
  97. &olds         setc &setting('string')
  98.               string asis
  99.               dc.w $7771
  100.               dc.b &len(&lab),'&lab'
  101.               string &olds
  102. @pastName
  103.               endif
  104.               mend
  105.  
  106. * You can use procname instead of proc
  107.  
  108.               macro
  109. &lab          procname &x
  110. &lab          proc     &x
  111.               if DebugSymbols<>0 then
  112.               brl @pastName
  113.               lclc &olds
  114. &olds         setc &setting('string')
  115.               string asis
  116.               dc.w $7771
  117.               dc.b &len(&lab),'&lab'
  118.               string &olds
  119. @pastName
  120.               endif
  121.               mend
  122.  
  123.  
  124. WRITING UTILITIES THAT RECOGNIZE INLINE NAMES
  125.  
  126. If you write a utility that recognizes inline procedure names in this format,
  127. check for a signature word of $777x, not specifically $7771.  This allows more
  128. information to be added to the format later (a signature of $7772 could mean
  129. there is a Pascal string followed by parameter-passing information, for
  130. example).
  131.